home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / dde / _pc / h / menu < prev    next >
Encoding:
Text File  |  1992-02-10  |  5.8 KB  |  164 lines
  1. (*
  2.  * Title:   menu.h
  3.  * Purpose: Menu creation/deletion/manipulation.
  4.  *
  5.  *)
  6.  
  7. # ifndef __menu_h
  8. # define __menu_h
  9.  
  10.  
  11. type menu__str = record end;
  12.      menu_ptr = ^menu;
  13.      menu = ^menu__str;     (* abstract menu handle *)
  14.  
  15. (*
  16.  * A menu description string defines a sequence of entries, with the
  17.  * following syntax (curly brakets mean 0 or more, square brackets mean
  18.  * 0 or 1):
  19.  *    opt ::= "!" or "~" or ">" or " "
  20.  *    sep ::= "," or "|"
  21.  *    l1 ::= any char but opt or sep
  22.  *    l2 ::= any char but sep
  23.  *    name ::= l1 <open brace> l2 <close brace>
  24.  *    entry ::= <open brace> opt <close brace> name
  25.  *    descr ::= entry <open brace> sep entry <close brace>
  26.  * Each entry defines a single entry in the menu. "|" as a separator means
  27.  * that there should be a gap or line between these menu components.
  28.  *
  29.  *   opt ! means, put a tick by it
  30.  *   opt ~ means, make it non-pickable
  31.  *   opt > means, has a dialogue box as "submenu"
  32.  *   space has no effect as an opt.
  33.  *)
  34.  
  35.  
  36. (* ----------------------------- menu_new ----------------------------------
  37.  * Description:   Creates a new menu structure, from the given textual
  38.  *                description (arranged as above).
  39.  *
  40.  * Parameters:    char *name -- name to appear in "title" of menu
  41.  *                char *description -- textual description of menu
  42.  * Returns:       pointer to menu structure created
  43.  * Other Info:    creates menu structure, with entries as given in textual
  44.  *                description. Entries are indexed from 1.
  45.  *                         eg. m=menu_new("Edit", ">Info Create Quit");
  46.  *                Handler needs to be attached using event_attachmenu.
  47.  *
  48.  *)
  49. function menu_new(name : string; description : string) : menu; extern;
  50.  
  51.  
  52. (* ------------------------------- menu_dispose ----------------------------
  53.  * Description:   Disposes of a menu structure.
  54.  *
  55.  * Parameters:    menu* -- the menu to be disposed of
  56.  *                int recursive -- non-zero ==recursively dispose of submenus
  57.  * Returns:       void.
  58.  * Other Info:    none.
  59.  *
  60.  *)
  61. procedure menu_dispose(mp : menu_ptr; recursive : integer); extern;
  62.  
  63.  
  64. (* ---------------------------- menu_extend --------------------------------
  65.  * Description:   Adds entries to the end of a menu
  66.  *
  67.  * Parameters:    menu -- the menu to which extension is being made
  68.  *                char *description -- textual description of extension.
  69.  * Returns:       void.
  70.  * Other Info:    extension has the format:
  71.  *                        [sep] entry <open brace> sep entry <close brace>
  72.  *                note: a menu which is already a submenu of another menu
  73.  *                      can't be extended
  74.  *
  75.  *)
  76. procedure menu_extend(m : menu; description : string); extern;
  77.  
  78.  
  79. (* --------------------------- menu_setflags -------------------------------
  80.  * Description:   Sets/changes flags on an already existing menu entry.
  81.  *
  82.  * Parameters:    menu -- the menu
  83.  *                int entry -- index into menu entries (from 1)
  84.  *                int tick -- non-zero == tick this entry
  85.  *                int fade -- non-zero == fade this entry (ie. unpickable)
  86.  * Returns:       void.
  87.  * Other Info:    none.
  88.  *
  89.  *)
  90. procedure menu_setflags(m : menu;
  91.                 entry : integer;
  92.                 tick, fade : boolean); extern;
  93.  
  94.  
  95. (* ----------------------------- menu_submenu ------------------------------
  96.  * Description:   Attaches a menu as a submenu of another at a given entry
  97.  *                in the parent menu.
  98.  *
  99.  * Parameters:    menu -- the menu
  100.  *                int entry -- entry at which to attach submenu
  101.  *                menu submenu -- pointer to the submenu
  102.  * Returns:       void.
  103.  * Other Info:    This replaces any previous submenu at this entry. Use
  104.  *                0 for submenu to remove an existing entry. Only a strict
  105.  *                hierarchy is allowed. When attached as a submenu, a menu
  106.  *                can't be extended or explicitly deleted.
  107.  *
  108.  *)
  109. procedure menu_submenu(m : menu; entry : integer; submenu : menu); extern;
  110.  
  111.  
  112. (* ------------------------- menu_make_writeable ---------------------------
  113.  * Description:   Makes a particular menu entry writeable.
  114.  *
  115.  * Parameters:    menu m -- the menu
  116.  *                int entry -- the entry to make writeable
  117.  *                char *buffer -- pointer to buffer to hold text of entry
  118.  *                int bufferlength -- size of buffer
  119.  *                char *validstring -- pointer to validation string
  120.  * Returns:       void.
  121.  * Other Info:    Lifetimes of buffer and validstring must be long enough.
  122.  *
  123.  *)
  124. procedure menu_make_writeable(m : menu;
  125.                 entry : integer;
  126.                 buffer : string;
  127.                 bufferlength : integer;
  128.                 validstring : string); extern;
  129.  
  130.  
  131. (* --------------------------- menu_make_sprite ----------------------------
  132.  * Description:   Makes a menu entry into a sprite.
  133.  *
  134.  * Parameters:    menu m -- the menu
  135.  *                int entry -- entry to be made into sprite
  136.  *                char *spritename -- name of the sprite
  137.  * Returns:       void.
  138.  * Other Info:    Entry which is initially a non-indirected text entry
  139.  *                is changed to an indirected sprite, with sprite area given
  140.  *                by resspr_area(), and name given by spritename.
  141.  *
  142.  *)
  143. procedure menu_make_sprite(m : menu;
  144.                 entry : integer;
  145.                 spritename : string); extern;
  146.  
  147.  
  148. (* ---------------------------- menu_syshandle -----------------------------
  149.  * Description:   Gives low-level handle to a menu.
  150.  *
  151.  * Parameters:    menu -- the menu
  152.  * Returns:       pointer to underlying WIMP menu structure.
  153.  * Other Info:    allows massaging of menu other than provided in this 
  154.  *                module. Returned pointer is in fact a pointer to a 
  155.  *                wimp_menustr (ie wimp_menuhdr followed by zero or more
  156.  *                wimp_menuitems).
  157.  *
  158.  *)
  159. function menu_syshandle(m : menu) : pointer; extern;
  160.  
  161. # endif
  162.  
  163. (* end menu.h *)
  164.